Skip to content

Conversation

@ymc9
Copy link
Member

@ymc9 ymc9 commented Nov 18, 2025

Summary by CodeRabbit

  • Documentation
    • Better-Auth guide updated with a sidebar label, clarified examples, and a recommended pattern to use an auth-enabled ORM client plus guidance on creating user-bound clients.
    • New Clerk authentication integration guide covering setup, model/configuration guidance, user sync, and creating user-bound ORM clients.
    • New custom authentication guide with required auth-field mapping, runtime user retrieval advice, and user-bound client examples.

@vercel
Copy link

vercel bot commented Nov 18, 2025

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Preview Comments Updated (UTC)
zenstack-new-site Ready Ready Preview Comment Nov 18, 2025 5:51pm

@coderabbitai
Copy link
Contributor

coderabbitai bot commented Nov 18, 2025

Walkthrough

Adds/edits documentation in v3.x auth integration: updates Better-Auth examples to use an auth-enabled ORM client (authDb.$setAuth(...)) and adds two new recipe pages for Clerk and custom authentication, both showing how to create user-bound ORM clients via $setAuth().

Changes

Cohort / File(s) Change Summary
Better-Auth update
versioned_docs/version-3.x/recipe/auth-integration/better-auth.md
Added sidebar_label metadata, clarified import comments, and replaced db.$setAuth(...) usages with authDb.$setAuth(...), plus guidance line about creating user-bound ORM clients after obtaining session data.
Clerk integration guide (new)
versioned_docs/version-3.x/recipe/auth-integration/clerk.md
New page describing Clerk setup with ZenStack, ZModel @@auth usage, Post model example, user sync guidance, and server-side examples that obtain Clerk session (auth()) and call $setAuth() on an auth-enabled ORM client.
Custom auth guide (new)
versioned_docs/version-3.x/recipe/auth-integration/custom.md
New page describing required auth fields (id, role, permissions), mapping auth() to a model/type, runtime user resolution (JWT/service), and example creating a user-bound ORM client via ZenStackClient.$setAuth(...).

Sequence Diagram(s)

sequenceDiagram
    autonumber
    actor Client
    participant Server
    participant AuthService as Auth Service
    participant AuthDB as authDb (ORM w/ access policy)

    Client->>Server: Request (authenticated)
    Server->>AuthService: retrieve session / current user
    AuthService-->>Server: user { id, role, ... }
    note right of Server `#DDEBF7`: create user-bound ORM client
    Server->>AuthDB: authDb.$setAuth({ userId, role, ... })
    AuthDB-->>Server: auth-enabled client ready
    Server->>AuthDB: perform DB operations (enforced by access policies)
    AuthDB-->>Server: query/mutation results
    Server-->>Client: response
Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

  • Docs-only changes, consistent patterns across files.
  • Pay attention to:
    • Correctness of updated code snippets (imports and authDb usage).
    • Accurate explanation of @@auth mapping and required auth fields.
    • Consistency between Clerk examples and server helper usage.

Possibly related PRs

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly summarizes the main change: migrating additional authentication guides to version 3. It directly matches the changeset which adds/updates three auth integration documentation files (Better-Auth, Clerk, and custom auth) for the v3 documentation.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
✨ Finishing touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Post copyable unit tests in a comment
  • Commit unit tests in branch doc/more-auth-guide

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 0365a5c and c82bc0a.

📒 Files selected for processing (1)
  • versioned_docs/version-3.x/recipe/auth-integration/clerk.md (1 hunks)
🚧 Files skipped from review as they are similar to previous changes (1)
  • versioned_docs/version-3.x/recipe/auth-integration/clerk.md

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 56847d8 and 0365a5c.

📒 Files selected for processing (3)
  • versioned_docs/version-3.x/recipe/auth-integration/better-auth.md (5 hunks)
  • versioned_docs/version-3.x/recipe/auth-integration/clerk.md (1 hunks)
  • versioned_docs/version-3.x/recipe/auth-integration/custom.md (1 hunks)
🧰 Additional context used
🪛 markdownlint-cli2 (0.18.1)
versioned_docs/version-3.x/recipe/auth-integration/clerk.md

11-11: Heading levels should only increment by one level at a time
Expected: h2; Actual: h3

(MD001, heading-increment)

🔇 Additional comments (5)
versioned_docs/version-3.x/recipe/auth-integration/custom.md (1)

1-59: Custom auth guide is well-structured and complete.

versioned_docs/version-3.x/recipe/auth-integration/clerk.md (1)

1-9: Clerk integration guide is comprehensive and clear.

The documentation properly covers setup, schema configuration, and the user-bound ORM client creation pattern with clear code examples for Next.js.

versioned_docs/version-3.x/recipe/auth-integration/better-auth.md (3)

3-3: Metadata update is appropriate.


29-31: Import comment and pattern are clear.

The clarifying comment for the auth-enabled ORM client and the shift to authDb import align with the v3 migration pattern shown in the other auth integration guides.


85-89: Consistent migration to user-bound ORM pattern.

Both code examples properly switch from db.$setAuth() to authDb.$setAuth(), maintaining consistency with the new authentication integration approach across all guides.

Also applies to: 120-121

@ymc9 ymc9 merged commit 0449518 into main Nov 18, 2025
4 checks passed
@ymc9 ymc9 deleted the doc/more-auth-guide branch November 18, 2025 17:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants